PATH  Mac OS X Server Documentation > Mac OS X Server Release Notes

[Back]

MacOS X Server Release Notes Copyright \xa9 1998 by Apple Computer, Inc. All Rights Reserved.

MacOS X Server Developer Release Notes:
Project Builder

Converting Existing Projects to the New Directory Structure

The Rhapsody system directory layout has been changed significantly in this release to eliminate references to Next and to be more consistent and uniform. Because of this change, existing projects that were created in Rhapsody DR1 or OpenStep 4.2 do not build properly, and might have problems indexing. If you do try to build such a project, you will see messages of the following form in the build detail window:

Makefile:52: /NextDeveloper/Makefiles/pb_makefiles/platform.make: No such file or directory
Makefile:56: /NextDeveloper/Makefiles/pb_makefiles/app.make: No such file or directory
gnumake: *** No rule to make target `app'. Stop.

Rhapsody DR2 provides tools to search your projects for any references to the old directory layout, and to convert your project files (PB.project) and Makefiles (including preambles and postambles) to the new directory layout.

These tools and documentation of them are available in:

/System/Developer/Makefiles/Conversion/DirectoryLayout

New Features

The following features are new in the Developer Release:

Class Browser

The Class Browser is a new Project Builder feature that you use primarily to browse the class hierarchy of a project and of the frameworks it depends on. You can also use it as an alternative way to navigate a project. And you can use it to access reference documentation.

You access the Class Browser by clicking this button on Project Builder's main window:

You can also display it by choosing Class Browser from the Tools menu. The Class Browser window is then displayed:

To support the Class Browser, the indexing process includes an extra step of collecting specific class-related information. You cannot use the Class Browser without indexing your project.

The Class Browser features a browser that displays the class hierarchy, usually starting with NSObject and NSProxy in the first column (more about this in Known Bugs); if you check the Show All Classes checkbox, it can also flatten the tree and show all known classes in the first column.

When you click a class name, the Class Browser shows the class's direct subclasses in the next column. Classes in bold face belong directly to your project and usually contain implementation code.

The instance variables and methods for a selected class are displayed below the class browser in two smaller browsers. If you check the Show Inherited the variables and methods includethose defined by the superclasses of the selected class. The method browser shows methods alphabetically; this is true even if the Show Inherited checkbox is turned on. When you click a method in the browser, Project Builder displays the file where the symbol is declared or defined, scrolled to the appropriate line.Those lines for symbols having documentation include an book icon; click the book icon to display the documentation. The variables and methods shown in bold face indicate symbols with available implementation code.

To look up a known class just type its name in the Select Class field or select any document in ProjectBuilder and choose Tools>Class Browser>Select Class (this item is disabled if the class is unknown or if the project is not indexed).

Enhancements

Support for categories was added for this release.

Limitations

The following items are current known limitations related to the Class Browser:

• Only the browsing of Objective-C classes is supported; browsing of Java classes is not yet supported.
  
  
• Classes may appear twice if they are defined in your project and also referenced by your project (from headers in a framework). For example this will happen in a aggregate project containing a framework and a tool that uses this framework.

For known bugs, see the "Known Bugs" section below.

Debugging

Project Builder has many new debugging features. For details see the Debugging release note.

Header-File Dependency Management

Project Builder can now maintain a list of header files included by each source file. If this feature is enabled, builds will regenerate an object file if the source file was edited or if any header file included by that source file was edited. This feature would, for instance, force a subclass to be recompiled if a superclass added an instance variable. To enable this feature for a project, open the Build Options panel and enter a "make depend" (as shown below) to create a dependency makefile. This operation takes approximately as long as a complete build, but after that the dependency makefile is automatically kept up to date by subsequent builds.

The dependency makefile resides in the build directory, and is destroyed along with that directory when you clean a project. To avoid having to "make depend" every time you clean, you can add the definition AUTOMATIC_DEPENDENCY_INFO=YES to the project's Makefile.preamble file.

Precompiled Headers

The standard system frameworks (Foundation, Application Kit, and others) now provide precompiled header files on Rhapsody.  Your source code compiles much faster if you include the precompiled header (#import <Foundation/Foundation.h>) rather than individual header files (#import <Foundation/NSArray.h>). Precompiled header files are not supported in this release of Yellow Box for Windows.

You can use precompiled headers in your own projects as well. Making public header files in frameworks into precompiled headers allows clients of the framework to compile their projects much more quickly.  Making project header files into precompiled headers allows files within the project to compile faster.  See the "Known Bugs" section below for more information about precompiled header files.

Trusted Precompiled Headers

In the past, the frameworks provided by Apple have contained a  precompiled header file (Foundation.p, AppKit.p, etc.).  When your source code imported the corresponding header (Foundation.h, AppKit.h, etc.) the compiler actually used the precompiled header instead.  This dramatically cut compile times, but presented a risk that the precompiled header file could get out of synch with the actual header.  To avoid this risk, the compiler checked the timestamp of the actual header and every header it included to ensure they were all older than the precompiled header file.  This ensured safety, but took considerable time because the precompiled header files generally include hundreds of other header files.

The compiler and makefiles have been changed to optimize this process.  After checking a precompiled header file and determining it to be up-to-date, the name of the header is written into a "trust file" named TrustedPrecomps.txt.  The next time the header file is included -- even by a different compiler invocation -- the compiler will see that it is trusted and will not examine the timestamps.  This trust file is stored in the project build directory and is deleted and recreated every time the project is built to ensure that the precompiled headers are not trusted for a dangerously long time.

One important implication of the use of trust files is that your compiler must understand the flag -precomp-trustfile.  If you are using a compiler other than the gcc that is shipped with this release of the developer environment you must disable trust files by adding the line "PRECOMP_CFLAGS = " to your Makefile.postamble.

Automatic Generation of .def Files

On Windows, the Microsoft linker requires symbols exported from a framework DLL to be explictly specified. One way of doing this is in a .def file in the project (for example, "MyFramework.def"). In prior releases, this file had to be manually created. Project Builder now generates a .def file for frameworks and dynamic libraries (that is, library projects producing DLLs). It re-creates the file the first time a project is built and, thereafter, updates it every time an object file changes. To get this feature, you must update to the new makefiles (See "New Makefiles," above).

If you currently have a .def file for a framework, and it is not highly customized, delete it and let Project Builder regenerate it for you. Otherwise, leave it where it is. Project Builder creates a .def file only if there isn't one already in the project.

The .def file that Project Builder creates is comprehensive, so if you want to create a customized .def file that is a subset of it, first build your project. Then add the generated .def file in derived_src to Supporting Files in your project and edit it as necessary.

Note: You hould use the CONSTANT keyword instead DATA in your .def file. The export of framework functions also requires a little extra code. For more on both of these items, see "Known Problems in this Release, " below. In creating the .def file for frameworks and dynamic libraries (DLLs), Project Builder handles Objective-C symbols and data but not functions. If you have functions in your framework that need to be callable from the outside, define certain macros in a header file and then use them in your function declarations. These macros allow you to export non-static functions from the DLL (FRAMEWORK _EXTERN) or to declare them as extern, but not exported (FRAMEWORK _PRIVATE_EXTERN). The following example shows how (substitute your own framework name for FRAMEWORK ):

#ifndef _FRAMEWORK DEFINES_H
#define _FRAMEWORK DEFINES_H
#if defined(WIN32)
//
// For Windows
//
 #ifndef _FRAMEWORK _BUILDING_DLL
#define _FRAMEWORK _WINDOWS_DLL __declspec(dllimport)
#else
#define _FRAMEWORK _WINDOWS_DLL __declspec(dllexport)
#endif
#ifdef __cplusplus
#define FRAMEWORK _EXTERN extern "C" _FRAMEWORK _WINDOWS_DLL
#define FRAMEWORK _PRIVATE_EXTERN extern
#else
#define FRAMEWORK _EXTERN _FRAMEWORK _WINDOWS_DLL extern
#define FRAMEWORK _PRIVATE_EXTERN extern
#endif

You need to import this header in all your other headers and declare your function prototypes accordingly. Then make sure you define FRAMEWORK _BUILDING_DLL when building your framework.

Warning: Don't define the same extern symbol twice, even in two separate frameworks that are both included into the same project. This can result in an error message of the following form from the Microsoft linker:

fatal error LNK1106: invalid file or disk full: cannot seek to 0x..."

CVS_Support Bundle is Unsupported

The CVS_Support bundle is not supported in this release. Although it is present on the system at /System/Developer/PBBundles/CVS_Support.bundle and can be loaded into Project Builder, there are a variety of problems with it that have existed since OpenStep 4.2. We plan to improve this support in a future release.

Escape Completion

The Escape key (Esc) now no longer does escape completion by default; instead, it cancels the current action (usually dismissing panels). To change Escape back to completion, create or edit the DefaultKeyBinding.dict file in ~/Library/KeyBindings so that it contains this line:

{
    "\033" = "complete";
}

Localization Support

ProjectBuilder's support for localization has been improved. The project browser will show the existing languages inside localizable suitcases. Resources not showing inside a language are global.

The ProjectTypes folder in the ProjectBuilder framework contains project types descriptions. Each type contains an Info.table file that specifies the localizable suitcases. For instance the Application project type declares:

Localizable_Keys = (INTERFACES, IMAGES, OTHER_RESOURCES, HELP_RESOURCES);

A localizable resource will show localization attributes in the File Inspector.

<<PBLocalization1.tiff's GIF equivalent goes here.>>

<<PBLocalization2.tiff's GIF equivalent goes here.>>

You can change the resource attributes to make it global or localized at any time. You can also add and remove languages to a localized resource. You need to click "Apply" for changes to take effect.

When a global resource is made local, ProjectBuilder will copy it to the requested languages folders (<language>.lproj) and then remove the global resource.

When a localized resource is made global, ProjectBuilder will copy the selected resource (from the selected language) into the parent folder and then remove all localized instances.

When adding and removing languages for a localized resource, ProjectBuilder will first use the selected resource to make copies in the added languages, and then will remove instances of the resource from the removed languages.

The format for the project description file PB.project has changed. The new version is 2.8.

The key LOCALIZABLE_FILES has been replaced with localized keys in the form <language>_KEY (for instance English_INTERFACES).

The generated Makefile now has variables in the form <language>_RESOURCES, <language>_HELP_FILES and <language>_WEBSERVER_RESOURCES.

The LANGUAGE variable has been removed and replaced with LANGUAGES.

The list of possible languages is defined by the ProjectBuilder framework as an array in the MainInfo.table property list ("HumanLanguages"). This list can be edited if needed for custom languages but this may require superuser privilege. Make sure that the other contents of the property list are not modified. The number of languages should not exceed 22 because of limited screen space in the inspector.

Preferences

There is a new option to open Documentation files using the workspace (for instance in a web browser). The number of columns in the project browser can be specified.

Known Problems

A number of problems that once caused Project Builder to crash spuriously -- for example when hitting arrow keys or closing projects -- have been fixed in this release.Other known major problems still unresolved include:

General

Reference	2213279, 1671760
Problem	Project Builder erroneously warns of unsaved nib files.
Description	If you attempt to build a project while you are viewing one of its nib files in Interface Builder, Project Builder will sometimes ask you if you want to save the nib file, even if you haven't actually edited it.
Workaround	If this problem persists, try saving the file in Interface Builder, or even quitting Interface Builder. If it continues to persist, quit Project Builder and relaunch it.

Builds

Reference	1674437
Problem	Rhapsody builds and Yellow Box for Windows builds try to use the same object files.
Description	If you build a project on Rhapsody, and then rebuild the project on Yellow Box for Windows, the Windows build will attempt to use the object files generated during the Rhapsody build. Since the object file formats are different, the build will fail.
Workaround	Use the Build Attributes inspector to specify separate "Build In" directories for the Rhapsody and the Yellow Box for Windows environments.

Class Browser

• Some classes don't show all instance variables.
• Root classes other than NSObject or NSProxy are not displayed.

Fixed Bugs

Single-File Compiles

Project Builder can now compile individual source files. When you are viewing a standard source file -- one ending in .m, .c, .M, .C, .cc, or .cxx -- you can click the small hammer icon    on the separator bar above the code view to compile the file. Single-file compiles are much faster than whole-project compiles and can help you detect syntax errors earlier in your code development.